home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / rbbs_pc / proedit.zip / RBBSPROT.DOC < prev   
Text File  |  1988-12-04  |  20KB  |  408 lines
  1. Extract from RBBS-PC v17.1A  Documentation Dealing with External Protocols
  2.  
  3. 21.  RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS
  4. ------------------------------------------------------
  5.  
  6. Before calling "external" protocol drivers, RBBS-PC will do the following:
  7.  
  8.     1. verify that the file exists if the file is to be downloaded.
  9.     2. for uploads, verify that the file name requested is  valid.
  10.     3. pass  the  communications  port  to  the  vendor's  protocol-
  11.        handling routine with the file opened and carrier detect on.
  12.  
  13. RBBS-PC  will  call  the  external protocol drivers either  via  the  SHELL
  14. command in BASIC or via a .BAT file.
  15.  
  16. 21.1  Parameters passed to a protocol driver.
  17. ----------------------------------------------
  18. RBBS-PC detects the installation of external file transfer protocols via an
  19. optional  RBBS-PC system file whose default name is PROTO.DEF.  If no  such
  20. file  exists,  all and only internal protocols will  be  available -- Ascii,
  21. Xmodem, XmodemCRC, Ymodem.  This file may be used to rename or delete  some
  22. or all of RBBS-PC's internal protocols.  If a PROTO.DEF file exists, all of
  23. RBBS-PC's  internal  protocols must be specified in it as  well.   Internal
  24. protocols are NOT automatically included when a PROTO.DEF file exists!
  25.  
  26. The  protocol definition file has thirteen (13) parameters passed for  each
  27. external  protocols  defined  for  RBBS-PC.  Each parameter  can  be  on  a
  28. separate  line  of  its own or all parameters can be on  a  single  line  (
  29. separated  by commas).  The parameters passed for each  protocol  specified
  30. are:
  31.  
  32.           Parameter       Description
  33.           1      Protocol Name
  34.           2      Security Level required to use protocol
  35.           3      Method to invoke protocol
  36.           4      Whether 8 bit connection required
  37.           5      Whether "reliable" connection required
  38.           6      Whether "batch" mode supported
  39.           7      Number of bytes in a block transferred
  40.           8      Indicate transfer always successful
  41.           9      Factor to estimate file transfer time
  42.          10      RBBS-PC "macro" to invoke before protocol
  43.          11      Method for checking transfer's success
  44.          12      Template to use for downloading
  45.          13      Template to use for uploading
  46.  
  47. * 1      Protocol Name
  48. Protocol  Name   --  The FIRST CHARACTER is the letter by  which  a  caller
  49.     selects  the  protocol.     The prompt for the  selection  of  protocol
  50.     includes  the  protocol  name.   It  is  recommended  that  the  second
  51.     character  be ")" to resemble the rest of the prompts in RBBS-PC,  e.g.
  52.     "Z)modem".  RBBS-PC defaults to putting each protocol on the same line,
  53.     separated  by  a comma, until the line gets too long.  Each  SYSOP  can
  54.     control  the  placement of the line by putting a carriage  return  line
  55.     feed  at  the end of the protocol name.  If this is  done,  the  entire
  56.     protocol  name  must be in parentheses.  For example,  instead  of  the
  57.     prompt
  58.  
  59. A)scii,X)modem,C)rcXmodem,Y)modem,N)one
  60.  
  61. a SYSOP may want the prompt to be
  62.  
  63. A)scii (text files only)
  64. X)modem checksum
  65. C)rc Xmodem
  66. Y)modem (1K Xmodem)
  67. N - None (cancel)
  68.  
  69.     Then  the protocol definition file , PROTO.DEF, should  be  constructed
  70.     using  quotes  (to include the carriage return/line feed in  the  first
  71.     parameter) as follows:
  72.  
  73. "A)scii (text files only)
  74. ",...
  75. "X)modem checksum
  76. ",...
  77. "C)rc Xmodem
  78. ",...
  79. "Y)modem (1K Xmodem)
  80. ",...
  81. "N - None (cancel)
  82. ",...
  83.  
  84.     with the remaining 12 parameters put where "..." occurs.
  85.  
  86. * 2      Security Level required to use protocol
  87. Security  Level  --  This is the minimum security to be  able  to  use  the
  88.     protocol being described.
  89.  
  90. * 3      Method to invoke protocol
  91. Method  to  Invoke Protocol -- A protocol can be invoked by  one  of  three
  92.     methods:
  93.              shell,
  94.              door, or
  95.              internal (S, D, or I).
  96.     If  "I"  is  specified, it must be immediately  followed  by  a  letter
  97.     specifying  what internal protocol to use, where the choices are A,  X,
  98.     C, Y, or N respectively for Ascii, Xmodem, Xmodem CRC, Ymodem, or  None
  99.     (cancel  transfer).  "IC" would mean to use RBBS-PC's  internal  Xmodem
  100.     CRC.   If no protocol is specified equivalent to the  internal  "None",
  101.     RBBS-PC will add it.  If the letter N is used for a transfer  protocol,
  102.     another protocol must be specified that is equivalent to "None".
  103.  
  104. * 4      Whether 8 bit connection required
  105. Whether to Require 8 Bit -- By putting "8" in this parameter, the SYSOP  is
  106.     specifying that the protocol requires the caller to be able to send  or
  107.     receive 8 data bits.  If 8 data bits is required and the caller is  not
  108.     at 8 bit, RBBS-PC will prompt the caller to change to 8 bit in order to
  109.     use the protocol.
  110.  
  111. * 5      Whether "reliable" connection required
  112. Whether  A  Reliable  Connections Is Required -- By  putting  "R"  in  this
  113.     parameter, the SYSOP is specifying that the protocol will not be  shown
  114.     or  made  available to the caller unless the  connections  is  reliable
  115.     (i.e. such as Microcom's MNP protocol that is built into many modems).
  116.  
  117. * 6      Whether "batch" mode supported
  118. Whether  Support  Batch -- By putting "B" in this parameter, the  SYSOP  is
  119.     indicating  that "batch" file transfers are allowed with the  protocol.
  120.     "Batch" means a multi-file download request will be processed together.
  121.     The  receive function in Qmodem's "batch" Ymodem attempts to write  the
  122.     file  being  received to the same letter drive and path name as  it  is
  123.     stored  on the sending PC.  Because it is unlikely that the PC  running
  124.     RBBS-PC will have the same disk letters and path names as the  callers,
  125.     it  is  recommended  that  QMODEM's "batch"  Ymodem  not  be  used  for
  126.     receiving files via "batch" Ymodem (use DSZ's instead).  RBBS-PC enters
  127.     an external protocol only once to do multiple file downloads.   RBBS-PC
  128.     has been tested with such "batch" protocols as Zmodem's DSZ,  Megalink,
  129.     and Sealink.
  130.  
  131. * 7      Number of bytes in a block transferred
  132. Blocksize  --  This parameter indicates the number of bytes in  each  block
  133.     transferred.   This  is only used to inform the caller  the  number  of
  134.     blocks  to  expect when downloading.  A zero in  this  parameters  will
  135.     cause RBBS-PC to report only the number of bytes to expect.  For Xmodem
  136.     or  XmodemCRC this value would be 128.  For Ymodem this value would  be
  137.     1024.
  138.  
  139. * 8      Indicate transfer always successful
  140. Indicate Transfers Always Successful -- If there is no way for the protocol
  141.     to  inform  RBBS-PC  if a transfer was successful, put a  "F"  in  this
  142.     parameter.   This  means  that  all  transfers  will  be  regarded   as
  143.     successful.
  144.  
  145.     Zmodem (DSZ) used in a multi-tasking DOS environment (i.e. where  there
  146.     can only be a single environment) and CLINK are examples of a protocols
  147.     that require this to be set.
  148.  
  149. * 9      Factor to estimate file transfer time
  150. Factor to Estimate File Transfer Time -- This is the decimal number used by
  151.     RBBS-PC to estimate the elapse time to download a file. The higher  the
  152.     number,  the  faster  the protocol and the  lower  the  time  estimate.
  153.     Standard equivalents in RBBS-PC are:
  154.  
  155.      Ascii .........  0.92
  156.      Xmodem ........  0.78
  157.      XmodemCRC .....  0.78
  158.      Kermit ........  0.78
  159.      Ymodem ........  0.87
  160.      Imodem ........  0.90
  161.      YmodemG .......  0.95
  162.      Windowed xmodem  0.78
  163.  
  164.     If no value is specified, a default of 0.87 will be used.
  165.  
  166. * 10      RBBS-PC "macro" to invoke before protocol
  167. RBBS-PC  "Macro" to Invoke Before Protocol -- This is the  RBBS-PC  "macro"
  168.     (i.e. a series of standard RBBS-PC commands) to invoke before  invoking
  169.     the protocol.  It can be used to display special messages, to delay the
  170.     start  of the protocol, or to prompt for special information passed  to
  171.     the protocol.
  172.  
  173. * 11      Method for checking transfer's success
  174. Method  for  Checking  Transfer's  Success -- This  is  required  only  for
  175.     external protocols.  This parameter indicates how RBBS-PC is to  detect
  176.     a file transfer's failure.  The format is "x=y=z" where:
  177.  
  178.            x is which parameter tells whether the transfer was successful,
  179.            y is the string which indicates failure, and
  180.            z is an optional parameter telling RBBS-PC whether to write out
  181.              information needed when DOORing to a protocol in advance of
  182.              the file exchange.
  183.  
  184.     For  QMXFER.EXE from John Friel and the Forbin Project, this  would  be
  185.     "4=F"  - meaning the 4th parameter indicates failure if it begins  with
  186.     "F".
  187.  
  188.     For  Zmodem  as  implemented in DSZ from  Omen  Technologies,  the
  189.     proper  choice  depends on whether SHELLing or  DOORing  is  used.
  190.     For  SHELLing, put in "1=E"  to indicate that the first  parameter
  191.     uses  "E" to indicate an error has occurred.  For DOORing, put  in
  192.     "4=E=A"  to indicate that the fourth parameter uses "E"  an  error
  193.     has  occured.   The "=A" means that RBBS-PC is to  do  an  advance
  194.     write  of  the filename and protocol used.  DSZ then  appends  its
  195.     error  report to the log file.   To the file "XFER-" plus  node  #
  196.     plus   ".DEF"   RBBS-PC   will  write  out   a   line   containing
  197.     "<filename>,,<protocol letter>".  Omitting an "=" causes a default
  198.     to  "4=F".  The file checked is "XFER-" plus the node number  plus
  199.     the extension "DEF".   On node 1 the file checked is "XFER-1.DEF".
  200.  
  201. * 12      Template to use for downloading
  202. Template  to  Use  for Downloading -- This is required  only  for  external
  203.     protocols.   It  tells  RBBS-PC  how to invoke  a  download.   See  the
  204.     following section on discussion of "templates".
  205.  
  206. * 13      Template to use for uploading
  207. Template  to  Use  for  Uploading -- This is  required  only  for  external
  208.     protocols.  It tells RBBS-PC how to invoke an upload.
  209.  
  210. 21.2  Calling external protocols using "templates"
  211. --------------------------------------------------
  212. A "template" is used to inform RBBS-PC how to invoke an external  protocol.
  213. The  first  word  of the template must be the  file  name  (including  file
  214. extension) of the program to invoke.  RBBS-PC will check to make sure  that
  215. the file exists.  If the file does not exits, the protocol will not be made
  216. available  to  the caller.  If the file does exists, the protocol  will  be
  217. shown to the caller.
  218.  
  219. RBBS-PC will dynamically substitute values for pre-defined strings inside a
  220. "template".   Each  supported string is enclosed in square  brackets.   The
  221. strings supported include:
  222.  
  223. [n]       where  n is a positive integer.  Substitutes value in  the  array
  224.           A$,  which can best be viewed as a work array.  Macros can  store
  225.           prompted values in specific elements in the array.
  226.  
  227. [FILE].   Name of the file (FILE.NAME$) to be transferred.
  228.  
  229. [BAUD].   Baud rate.  Speed at which the caller dialed RBBS-PC.
  230.  
  231. [PARITY]. Parity used by the caller.
  232.  
  233. [PORT].   DOS  device name for the communications port to be used  for  the
  234.           file transfer (COM1,COM2, etc.).
  235.  
  236. [PORT#]   Number  of  the  communications  port to be  used  for  the  file
  237.           transfer (1,2,3, etc.).
  238.  
  239. [NODE].   Number  of  the RBBS-PC node invoking the file  transfer  (1,2,3,
  240.           etc.).
  241.  
  242. [PROTO].  Letter of the protocol for the file transfer.
  243.  
  244. Everything else in a template will be passed intact.  If the external  file
  245. transfer is to be invoked via a SHELL, it is recommended that the  external
  246. file  transfer  program  be  SHELLed to directly.   If  the  external  file
  247. transfer is to be invoked via a DOOR, it can be either
  248.  
  249.      1.)  DOORed to directly using the same template as for SHELLing, or
  250.  
  251.      2.)  DOORed to indirectly via a .BAT file with the command  parameters
  252.           passed to it by RBBS-PC.  For example, a "door" for QMXFER  might
  253.           have a download template of:
  254.  
  255.           "RBBSQM.BAT [FILE] [PORT] [BAUD] [PROTO]"
  256.  
  257.           and the file RBBSQM.BAT have the following in it:
  258.  
  259.           C:QMXFER.COM -s -f %1 -l %2 -c -b %3 -p %4
  260.  
  261.           DOS substitutes the passed parameters for the variables beginning
  262.           with  the percent sign.  .BAT files are needed in doors if  there
  263.           are  additional programs to run before or after the  actual  file
  264.           transfer.
  265.  
  266. The  following  examples should provide some help in understanding  how  to
  267. invoke external protocols:
  268.  
  269. Example #1:
  270.  
  271. Z)ippy,5,S,8,,,,,0.98,,,"c:\proto\zippy -s [FILE]","c:\proto\zippy -r [FILE]"
  272.  
  273. Can be interpreted to be:
  274.      used "Z" as invoking letter,
  275.      put "Z)ippy" in the prompt,
  276.      the minimum security to use this protocol is 5,
  277.      the protocol will be invoked via a SHELL command,
  278.      an 8-bit connection is required,
  279.      estimate the download time as 0.98 times as fast as normal,
  280.      use normal RBBS-PC type of report to check for a successful transfer,
  281.      invoke the protocol for downloads using the following string:
  282.           "c:\proto\zippy -s [FILE]"
  283.      and invoke the protocol for uploads using the following string:
  284.           "c:\proto\zmodem -r [FILE]"
  285.      where the file name is substituted for "[FILE]" in either case.
  286.  
  287. Example #2:
  288.  
  289. X)modem,5,IX,8,,,128,,0.8,,,,
  290.  
  291. Can be interpreted to be:
  292.      used "X" as invoking letter,
  293.      put "X)modem" in the prompt,
  294.      the minimum security to use this protocol is 5,
  295.      the protocol is an internal RBBS-PC protocol,
  296.      an 8-bit connection is required, and
  297.      estimate the download time as 0.8 times as fast as normal.
  298.  
  299. 21.3  Parameters Returned by a Protocol Driver
  300. ----------------------------------------------
  301. All  protocol  drivers are expected to return information  about  the  file
  302. transfer in a file named XFER-xx.DEF where the value for xx is the node  ID
  303. (1 to 36).  If the protocol cannot accommodate this minimal requirement, it
  304. can still be used by telling RBBS-PC to indicate file transfers are  always
  305. successful -- section 21.1, parameter 9.
  306.  
  307. The  one  item  of  information RBBS-PC requires to  be  returned  from  an
  308. external protocol drive is whether or not the file transfer was successful.
  309. The failure indicator MUST BE:
  310.  
  311.    a.)  the first character of
  312.    b.)  any parameter
  313.  
  314. in the file XFER-xx.DEF.  To show that file transfer failures are indicated
  315. by  the  first  parameter  and the letter  "E"  in  the  file  XFER-xx.DEF,
  316. parameter 11 (as described in section 21.1) would be written as "1=E".   To
  317. show that file transfer failures are indicated by the fourth parameter  and
  318. the  letter  "F",  parameter 11 (as described in  section  21.1)  would  be
  319. written as "4=F".
  320.  
  321. No  other information is required when SHELLing to external  file  transfer
  322. protocols.   However, when DOORing to external file transfer protocols  the
  323. log file for the transfer MUST HAVE the file name as the first parameter.
  324.  
  325. Protocol drivers that do not have the file name as the first parameter  can
  326. still be used by telling RBBS-PC to write out three parameters (file  name,
  327. an  empty parameter, and the letter of the file transfer  protocol)  before
  328. invoking  the external file protocol.  This is done by using  parameter  11
  329. (as described in section 21.1).  As an example, to DOOR to an external file
  330. transfer  protocol  that  indicates a file transfer failure  by  using  the
  331. letter "F" in the fourth parameter, but which does not return the file name
  332. used,  parameter  11  (as described in section 21.1) would  be  written  as
  333. "4=F=A".   The external protocol would then append its own  information  to
  334. the log file.
  335.  
  336. 21.4  The Protocol Drivers Tested With RBBS-PC
  337. ----------------------------------------------
  338. RBBS-PC has been tested with the following protocol drivers:
  339.  
  340. CLINK -- From System Enhancement Associates.  Supports batch file transfers
  341.     but requires that transfers always be assumed successful.
  342.  
  343. DSZ -- From Omen Technologies.  Supports Ymodem, Ymodem Batch, YmodemG, and
  344.     Zmodem.   YmodemG  requires  a "reliable"  connection.   DSZ  logs  the
  345.     results  of the file transfers to a file specified in  the  environment
  346.     variable DSZLOG.  Therefore, the AUTOEXEC.BAT file for an RBBS-PC  that
  347.     uses DSZ should specify
  348.  
  349.      "SET DSZLOG=XFER-x.DEF"
  350.  
  351.     where  x  is the node number.   DSZ seems unable to create a  log  file
  352.     whenever a drive or path is specified.  If invoking ZMODEM via the DOOR
  353.     mechanism,  use the "=A" option at the end of the success method  check
  354.     so that RBBS-PC will append the information to the DSZ log it needs and
  355.     DSZ  will then append the success report.  In a multi-user  environment
  356.     where  a  different  environment  variable for each  node  can  not  be
  357.     specified  (i.e. all nodes must share the same DSZ log  file),  specify
  358.     that  a all transfers are always successful for protocols  handled  via
  359.     DSZ.   See the discussion of parameter 11 in section 21.1  for  further
  360.     considerations when using DSZ.
  361.  
  362. MLINK -- MEGALINK protocol supports batch file transfers but requires  that
  363.     transfers always be assumed successful.
  364.  
  365. PC-KERMIT  --  from Columbia University.  PCKERMIT.EXE is supplied  by  The
  366.     Source  as  a  public service and consists  of  sliding  window  KERMIT
  367.     protocol. The development of "windowing" within the KERMIT architecture
  368.     (i.e.  Super KERMIT) was funded by The Source and implemented by  Larry
  369.     Jordan and Jan van der Eijk.
  370.  
  371.     Columbia  University  holds  the copyright  and  maintains  the  Kermit
  372.     protocol. Like RBBS-PC, Columbia University allows KERMIT to be  passed
  373.     along  to others and "ask only that profit not be your goal, credit  be
  374.     given where it is due, and that new material be sent back to us so that
  375.     we   can  maintain  a  definitive  and  comprehensive  set  of   KERMIT
  376.     implementations".
  377.  
  378.     PCKERMIT.EXE  is  not  a terminal program.  It  simply  implements  the
  379.     Kermit protocol, including the sliding window extension.  It will  work
  380.     with  older  "Kermit Classic" implementations as  well,  via  automatic
  381.     negotiation  between the two Kermit programs.  PCKERMIT.EXE runs  as  a
  382.     "one-shot"  execution  then  returns to  RBBS-PC.   PCKERMIT  does  not
  383.     establish   a  carrier  with  a  remote  system.   The  connection   is
  384.     established  by  RBBS-PC.   File  transfers  must  always  be   assumed
  385.     successful.
  386.  
  387. QMXFER  --  is  supplied  by The Forbin Project as  a  public  service  and
  388.     supports   five  different  protocols  --  XMODEM  (checksum),   XMODEM
  389.     (cyclical  redundancy check), YMODEM, YMODEMG, and IMODEM.  QMXFER  was
  390.     implemented by John Friel III, author of QMODEM. YMODEM and YMODEMG are
  391.     protocols designed by Chuck Frosberg.  IMODEM is a protocol designed by
  392.     John  Friel.  The later two are designed to work when the link  between
  393.     the two modems is "error free" (i.e. both modems have the MNP  protocol
  394.     built  in)>  QMXFER.COM runs as a "one-shot" execution then returns  to
  395.     RBBS-PC.   QMXFER  does not establish a carrier with a  remote  system.
  396.     The  connection is established by RBBS-PC.  File transfer failures  are
  397.     indicated by an "F" in the fourth parameter of the log file returned to
  398.     RBBS-PC.
  399.  
  400. WXMODEM  --  is  supplied by The Forbin Project as  a  public  service  and
  401.     supports the window XMODEM protocol designed by Pete Boswell.  Like all
  402.     of  RBBS-PC's  protocol  drivers,  WXMODEM.COM  runs  as  a  "one-shot"
  403.     execution  then  returns  to RBBS-PC.  WXMODEM  does  not  establish  a
  404.     carrier  with a remote system.  The connection is established by  RBBS-
  405.     PC.   File  transfer  failures are indicated by an "F"  in  the  fourth
  406.     parameter of the log file returned to RBBS-PC.
  407.  
  408.